Monitoring / Statistics

Actuator endpoints used to monitor and diagnose the internal configuration of the CAS server are typically exposed over the endpoint /actuator.

Actuator Endpoints

The following endpoints are provided:

CAS version information and other system traits.

Map

InfoEndpoint.info()

org.springframework.boot.actuate.info.InfoEndpoint

Analyze application startup events, beans and load and optionally report events to Java Flight Recorder.

StartupResponse

StartupEndpoint.startupSnapshot()

org.springframework.boot.actuate.startup.StartupEndpoint

Analyze application startup events, beans and load and optionally report events to Java Flight Recorder.

StartupResponse

StartupEndpoint.startup()

org.springframework.boot.actuate.startup.StartupEndpoint

Produces a thread dump for the running CAS server.

ThreadDumpDescriptor

ThreadDumpEndpoint.threadDump()

org.springframework.boot.actuate.management.ThreadDumpEndpoint

Produces a thread dump for the running CAS server.

String text/plain;charset=UTF-8

ThreadDumpEndpoint.textThreadDump()

org.springframework.boot.actuate.management.ThreadDumpEndpoint

Reports back general health status of the system, produced by various monitors.

HealthComponent

HealthEndpoint.health()

org.springframework.boot.actuate.health.HealthEndpoint

Reports back general health status of the system, produced by various monitors.

HealthComponent

HealthEndpoint.healthForPath(java.lang.String…)

org.springframework.boot.actuate.health.HealthEndpoint

Runtime metrics and stats.

MetricResponse

MetricsEndpoint.metric(java.lang.String,java.util.List)

org.springframework.boot.actuate.metrics.MetricsEndpoint

Runtime metrics and stats.

ListNamesResponse

MetricsEndpoint.listNames()

org.springframework.boot.actuate.metrics.MetricsEndpoint

Displays HTTP trace information (by default, the last 100 HTTP request-response exchanges).

HttpTraceDescriptor

HttpTraceEndpoint.traces()

org.springframework.boot.actuate.trace.http.HttpTraceEndpoint

Describes how requests are mapped and handled by CAS.

ApplicationMappings

MappingsEndpoint.mappings()

org.springframework.boot.actuate.web.mappings.MappingsEndpoint

Displays the scheduled tasks in CAS.

ScheduledTasksReport

ScheduledTasksEndpoint.scheduledTasks()

org.springframework.boot.actuate.scheduling.ScheduledTasksEndpoint

Report back scheduled groups and triggers for Quartz.

QuartzReport

QuartzEndpoint.quartzReport()

org.springframework.boot.actuate.quartz.QuartzEndpoint


Metrics

Metrics allow to gain insight into the running CAS software, and provide ways to measure the behavior of critical components. See this guide for more info.

Distributed Tracing

Support for distributed tracing of requests is enabled by including the following dependency in the WAR overlay:

1
2
3
4
5
<dependency>
  <groupId>org.apereo.cas</groupId>
  <artifactId>cas-server-support-sleuth</artifactId>
  <version>${cas.version}</version>
</dependency>
1
implementation "org.apereo.cas:cas-server-support-sleuth:${project.'cas.version'}"
1
2
3
4
5
6
7
8
9
dependencyManagement {
  imports {
    mavenBom "org.apereo.cas:cas-server-support-bom:${project.'cas.version'}"
  }
}

dependencies {  
  implementation "org.apereo.cas:cas-server-support-sleuth"
}

image

For most users Sleuth should be invisible, and all interactions with external systems should be instrumented automatically.

Trace data is captured automatically and passed along to Zipkin, which helps gather timing data needed to troubleshoot latency problems.

The following settings and properties are available from the CAS configuration catalog:

The configuration settings listed below are tagged as Required in the CAS configuration metadata. This flag indicates that the presence of the setting may be needed to activate or affect the behavior of the CAS feature and generally should be reviewed, possibly owned and adjusted. If the setting is assigned a default value, you do not need to strictly put the setting in your copy of the configuration, but should review it nonetheless to make sure it matches your deployment expectations.

The configuration settings listed below are tagged as Optional in the CAS configuration metadata. This flag indicates that the presence of the setting is not immediately necessary in the end-user CAS configuration, because a default value is assigned or the activation of the feature is not conditionally controlled by the setting value.

The configuration settings listed below are tagged as Third Party in the CAS configuration metadata. This flag indicates that the configuration setting is not controlled, owned or managed by the CAS ecosystem, and affects functionality that is offered by a third-party library, such as Spring Boot or Spring Cloud to CAS. For additional info, you might have to visit the third-party source to find more details.

  • spring.sleuth.async.configurer.enabled=true
  • Enable default AsyncConfigurer.

  • spring.sleuth.async.enabled=true
  • Enable instrumenting async related components so that the tracing information is passed between threads.

    org.springframework.cloud.sleuth.autoconfig.instrument.async.SleuthAsyncProperties.

  • spring.sleuth.async.ignored-beans=
  • List of java.util.concurrent.Executor bean names that should be ignored and not wrapped in a trace representation.

    org.springframework.cloud.sleuth.autoconfig.instrument.async.SleuthAsyncProperties.

  • spring.sleuth.baggage.correlation-enabled=true
  • Enables correlating the baggage context with logging contexts.

    org.springframework.cloud.sleuth.autoconfig.SleuthBaggageProperties.

  • spring.sleuth.baggage.correlation-fields=
  • org.springframework.cloud.sleuth.autoconfig.SleuthBaggageProperties.

  • spring.sleuth.baggage.local-fields=
  • org.springframework.cloud.sleuth.autoconfig.SleuthBaggageProperties.

  • spring.sleuth.baggage.remote-fields=
  • List of fields that are referenced the same in-process as it is on the wire. For example, the field "x-vcap-request-id" would be set as-is including the prefix.

    org.springframework.cloud.sleuth.autoconfig.SleuthBaggageProperties.

  • spring.sleuth.baggage.tag-fields=
  • org.springframework.cloud.sleuth.autoconfig.SleuthBaggageProperties.

  • spring.sleuth.circuitbreaker.enabled=true
  • Enable Spring Cloud CircuitBreaker instrumentation.

    org.springframework.cloud.sleuth.autoconfig.instrument.circuitbreaker.SleuthCircuitBreakerProperties.

  • spring.sleuth.enabled=true
  • org.springframework.cloud.sleuth.autoconfig.brave.SleuthProperties.

  • spring.sleuth.feign.enabled=true
  • Enable span information propagation when using Feign.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.client.feign.SleuthFeignProperties.

  • spring.sleuth.feign.processor.enabled=true
  • Enable post processor that wraps Feign Context in its tracing representations.

  • spring.sleuth.function.enabled=true
  • Enable instrumenting of Spring Cloud Function and Spring Cloud Function based projects (e.g. Spring Cloud Stream).

  • spring.sleuth.grpc.enabled=true
  • Enable span information propagation when using GRPC.

  • spring.sleuth.http.enabled=true
  • Enables HTTP support.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthHttpProperties.

  • spring.sleuth.integration.enabled=true
  • Enable Spring Integration sleuth instrumentation.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthIntegrationMessagingProperties.

  • spring.sleuth.integration.patterns=!hystrixStreamOutput**!channel*
  • An array of patterns against which channel names will be matched. @see org.springframework.integration.config.GlobalChannelInterceptor#patterns() Defaults to any channel name not matching the Hystrix Stream and functional Stream channel names.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthIntegrationMessagingProperties.

  • spring.sleuth.integration.websockets.enabled=true
  • Enable tracing for WebSockets.

  • spring.sleuth.messaging.enabled=false
  • Should messaging be turned on.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties.

  • spring.sleuth.messaging.jms.enabled=true
  • Enable tracing of JMS.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties$Jms.

  • spring.sleuth.messaging.jms.remote-service-name=jms
  • JMS remote service name.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties$Jms.

  • spring.sleuth.messaging.kafka.enabled=true
  • Enable tracing of Kafka.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties$Kafka.

  • spring.sleuth.messaging.kafka.mapper.enabled=true
  • Enable DefaultKafkaHeaderMapper tracing for Kafka.

  • spring.sleuth.messaging.kafka.remote-service-name=kafka
  • Kafka remote service name.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties$Kafka.

  • spring.sleuth.messaging.kafka.streams.enabled=false
  • Should Kafka Streams be turned on.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties$Kafka$Streams.

  • spring.sleuth.messaging.rabbit.enabled=true
  • Enable tracing of RabbitMQ.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties$Rabbit.

  • spring.sleuth.messaging.rabbit.remote-service-name=rabbitmq
  • Rabbit remote service name.

    org.springframework.cloud.sleuth.autoconfig.instrument.messaging.SleuthMessagingProperties$Rabbit.

  • spring.sleuth.mongodb.enabled=true
  • Enable tracing for MongoDb.

  • spring.sleuth.opentracing.enabled=true
  • Enables OpenTracing support.

    org.springframework.cloud.sleuth.autoconfig.SleuthOpentracingProperties.

  • spring.sleuth.propagation.type=
  • Tracing context propagation types.

    org.springframework.cloud.sleuth.autoconfig.brave.SleuthPropagationProperties.

  • spring.sleuth.quartz.enabled=true
  • Enable tracing for Quartz.

  • spring.sleuth.reactor.decorate-on-each=true
  • When true decorates on each operator, will be less performing, but logging will always contain the tracing entries in each operator. When false decorates on last operator, will be more performing, but logging might not always contain the tracing entries. Deprecation: use explicit value via SleuthReactorProperties#instrumentationType

    org.springframework.cloud.sleuth.autoconfig.instrument.reactor.SleuthReactorProperties.

    Deprecation status is WARNING with a replacement setting: spring.sleuth.reactor.instrumentation-type=DECORATE_ON_EACH.

  • spring.sleuth.reactor.enabled=true
  • When true enables instrumentation for reactor.

    org.springframework.cloud.sleuth.autoconfig.instrument.reactor.SleuthReactorProperties.

  • spring.sleuth.reactor.instrumentation-type=
  • org.springframework.cloud.sleuth.autoconfig.instrument.reactor.SleuthReactorProperties.

  • spring.sleuth.redis.enabled=true
  • Enable span information propagation when using Redis.

    org.springframework.cloud.sleuth.autoconfig.brave.instrument.redis.TraceRedisProperties.

  • spring.sleuth.redis.remote-service-name=redis
  • Service name for the remote Redis endpoint.

    org.springframework.cloud.sleuth.autoconfig.brave.instrument.redis.TraceRedisProperties.

  • spring.sleuth.rpc.enabled=true
  • Enable tracing of RPC.

  • spring.sleuth.rxjava.schedulers.hook.enabled=true
  • Enable support for RxJava via RxJavaSchedulersHook.

    org.springframework.cloud.sleuth.autoconfig.instrument.rxjava.SleuthRxJavaSchedulersProperties$Hook.

  • spring.sleuth.rxjava.schedulers.ignoredthreads=HystrixMetricPoller^RxComputation.*$
  • Thread names for which spans will not be sampled.

    org.springframework.cloud.sleuth.autoconfig.instrument.rxjava.SleuthRxJavaSchedulersProperties.

  • spring.sleuth.sampler.probability=
  • Probability of requests that should be sampled. E.g. 1.0 - 100% requests should be sampled. The precision is whole-numbers only (i.e. there's no support for 0.1% of the traces).

    org.springframework.cloud.sleuth.autoconfig.brave.SamplerProperties.

  • spring.sleuth.sampler.rate=10
  • A rate per second can be a nice choice for low-traffic endpoints as it allows you surge protection. For example, you may never expect the endpoint to get more than 50 requests per second. If there was a sudden surge of traffic, to 5000 requests per second, you would still end up with 50 traces per second. Conversely, if you had a percentage, like 10%, the same surge would end up with 500 traces per second, possibly overloading your storage. Amazon X-Ray includes a rate-limited sampler (named Reservoir) for this purpose. Brave has taken the same approach via the brave.sampler.RateLimitingSampler.

    org.springframework.cloud.sleuth.autoconfig.brave.SamplerProperties.

  • spring.sleuth.sampler.refresh.enabled=true
  • Enable refresh scope for sampler.

  • spring.sleuth.scheduled.enabled=true
  • Enable tracing for org.springframework.scheduling.annotation.Scheduled.

    org.springframework.cloud.sleuth.autoconfig.instrument.scheduling.SleuthSchedulingProperties.

  • spring.sleuth.scheduled.skip-pattern=
  • Pattern for the fully qualified name of a class that should be skipped.

    org.springframework.cloud.sleuth.autoconfig.instrument.scheduling.SleuthSchedulingProperties.

  • spring.sleuth.span-filter.additional-span-name-patterns-to-ignore=
  • Additional list of span names to ignore. Will be appended to #spanNamePatternsToSkip.

    org.springframework.cloud.sleuth.autoconfig.SleuthSpanFilterProperties.

  • spring.sleuth.span-filter.enabled=false
  • Will turn on the default Sleuth handler mechanism. Might ignore exporting of certain spans;

    org.springframework.cloud.sleuth.autoconfig.SleuthSpanFilterProperties.

  • spring.sleuth.span-filter.span-name-patterns-to-skip=^catalogWatchTaskScheduler$
  • List of span names to ignore. They will not be sent to external systems.

    org.springframework.cloud.sleuth.autoconfig.SleuthSpanFilterProperties.

  • spring.sleuth.supports-join=true
  • True means the tracing system supports sharing a span ID between a client and server.

    org.springframework.cloud.sleuth.autoconfig.brave.SleuthProperties.

  • spring.sleuth.trace-id128=false
  • When true, generate 128-bit trace IDs instead of 64-bit ones.

    org.springframework.cloud.sleuth.autoconfig.brave.SleuthProperties.

  • spring.sleuth.tracer.mode=
  • Set which tracer implementation should be picked.

    org.springframework.cloud.sleuth.autoconfig.SleuthTracerProperties.

  • spring.sleuth.web.additional-skip-pattern=
  • Additional pattern for URLs that should be skipped in tracing. This will be appended to the SleuthWebProperties#skipPattern.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties.

  • spring.sleuth.web.client.enabled=true
  • Enable interceptor injecting into org.springframework.web.client.RestTemplate.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties$Client.

  • spring.sleuth.web.client.skip-pattern=
  • Pattern for URLs that should be skipped in client side tracing.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties$Client.

  • spring.sleuth.web.enabled=true
  • When true enables instrumentation for web applications.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties.

  • spring.sleuth.web.filter-order=0
  • Order in which the tracing filters should be registered.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties.

  • spring.sleuth.web.ignore-auto-configured-skip-patterns=false
  • If set to true, auto-configured skip patterns will be ignored.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties.

  • spring.sleuth.web.servlet.enabled=true
  • Enable servlet instrumentation.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties$Servlet.

  • spring.sleuth.web.skip-pattern=/api-docs.*|/swagger.*|.*\.png|.*\.css|.*\.js|.*\.html|/favicon.ico|/hystrix.stream
  • Pattern for URLs that should be skipped in tracing.

    org.springframework.cloud.sleuth.autoconfig.instrument.web.SleuthWebProperties.

  • spring.sleuth.web.webclient.enabled=true
  • Enable tracing instrumentation for WebClient.

  • spring.zipkin.activemq.message-max-bytes=100000
  • Maximum number of bytes for a given message with spans sent to Zipkin over ActiveMQ.

  • spring.zipkin.activemq.queue=zipkin
  • Name of the ActiveMQ queue where spans should be sent to Zipkin.

  • spring.zipkin.api-path=
  • The API path to append to baseUrl (above) as suffix. This applies if you use other monitoring tools, such as New Relic. The trace API doesn't need the API path, so you can set it to blank ("") in the configuration.

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties.

  • spring.zipkin.base-url=http://localhost:9411/
  • URL of the zipkin query server instance. You can also provide the service id of the Zipkin server if Zipkin's registered in service discovery (e.g. https://zipkinserver/).

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties.

  • spring.zipkin.compression.enabled=false
  • org.springframework.cloud.sleuth.zipkin2.ZipkinProperties$Compression.

  • spring.zipkin.discovery-client-enabled=
  • If set to false, will treat the ZipkinProperties#baseUrl as a URL always.

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties.

  • spring.zipkin.enabled=true
  • Enables sending spans to Zipkin.

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties.

  • spring.zipkin.encoder=
  • Encoding type of spans sent to Zipkin. Set to SpanBytesEncoder#JSON_V1 if your server is not recent.

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties.

  • spring.zipkin.kafka.topic=zipkin
  • Name of the Kafka topic where spans should be sent to Zipkin.

  • spring.zipkin.locator.discovery.enabled=false
  • Enabling of locating the host name via service discovery.

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties$Locator$Discovery.

  • spring.zipkin.message-timeout=1
  • Timeout in seconds before pending spans will be sent in batches to Zipkin.

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties.

  • spring.zipkin.rabbitmq.addresses=
  • Addresses of the RabbitMQ brokers used to send spans to Zipkin

  • spring.zipkin.rabbitmq.queue=zipkin
  • Name of the RabbitMQ queue where spans should be sent to Zipkin.

  • spring.zipkin.sender.type=
  • Means of sending spans to Zipkin.

    org.springframework.cloud.sleuth.autoconfig.zipkin2.ZipkinSenderProperties.

  • spring.zipkin.service.name=
  • The name of the service, from which the Span was sent via HTTP, that should appear in Zipkin.

    org.springframework.cloud.sleuth.zipkin2.ZipkinProperties$Service.

    Configuration Metadata

    The collection of configuration properties listed in this section are automatically generated from the CAS source and components that contain the actual field definitions, types, descriptions, modules, etc. This metadata may not always be 100% accurate, or could be lacking details and sufficient explanations.

    Be Selective

    This section is meant as a guide only. Do NOT copy/paste the entire collection of settings into your CAS configuration; rather pick only the properties that you need. Do NOT enable settings unless you are certain of their purpose and do NOT copy settings into your configuration only to keep them as reference. All these ideas lead to upgrade headaches, maintenance nightmares and premature aging.

    YAGNI

    Note that for nearly ALL use cases, declaring and configuring properties listed here is sufficient. You should NOT have to explicitly massage a CAS XML/Java/etc configuration file to design an authentication handler, create attribute release policies, etc. CAS at runtime will auto-configure all required changes for you. If you are unsure about the meaning of a given CAS setting, do NOT turn it on without hesitation. Review the codebase or better yet, ask questions to clarify the intended behavior.

    Naming Convention

    Property names can be specified in very relaxed terms. For instance cas.someProperty, cas.some-property, cas.some_property are all valid names. While all forms are accepted by CAS, there are certain components (in CAS and other frameworks used) whose activation at runtime is conditional on a property value, where this property is required to have been specified in CAS configuration using kebab case. This is both true for properties that are owned by CAS as well as those that might be presented to the system via an external library or framework such as Spring Boot, etc. When possible, properties should be stored in lower-case kebab format, such as cas.property-name=value.S ettings and properties that are controlled by the CAS platform directly always begin with the prefix cas. All other settings are controlled and provided to CAS via other underlying frameworks and may have their own schemas and syntax. BE CAREFUL with the distinction. Unrecognized properties are rejected by CAS and/or frameworks upon which CAS depends. This means if you somehow misspell a property definition or fail to adhere to the dot-notation syntax and such, your setting is entirely refused by CAS and likely the feature it controls will never be activated in the way you intend.

    Validation

    Configuration properties are automatically validated on CAS startup to report issues with configuration binding, specially if defined CAS settings cannot be recognized or validated by the configuration schema. The validation process is on by default and can be skipped on startup using a special system property SKIP_CONFIG_VALIDATION that should be set to true. Additional validation processes are also handled via Configuration Metadata and property migrations applied automatically on startup by Spring Boot and family.

    Indexed Settings

    CAS settings able to accept multiple values are typically documented with an index, such as cas.some.setting[0]=value. The index [0] is meant to be incremented by the adopter to allow for distinct multiple configuration blocks.

    Troubleshooting

    To enable additional logging, modify the logging configuration file to add the following:

    1
    2
    3
    4
    
     <Logger name="org.springframework.cloud" level="debug" additivity="false">
        <AppenderRef ref="casConsole"/>
        <AppenderRef ref="casFile"/>
    </Logger>